Microsoft CodeView and Utilities
================================
CHAPTER 2 ___ THE CODEVIEW DISPLAY
(Second half)

2.1.3  Using Menu Selections

This section describes the selections on each of the CodeView menus.  These
selections can be made with the keyboard, as described in Section 2.1.2.
Note that although the Trace and Go commands appear on the menu bar, they are
not menus.  These titles are provided primarily for mouse users.

2.1.3.1  The File Menu

The File menu includes selections for working on the current source or program
file.  The File menu is shown in Figure 2.2, and the selections are explained
below.

Selection	Action
---------------------
Open...		Opens a new file.

		When you make this selection, a dialog box appears asking for
		the name of the new file you want to open.  Type the name of a
		source file, an include file, or any other test file.  The
		text of the new file replaces the  current contents of the
		display window (if you are in assembly mode, the CodeView
		debugger will switch to source mode).  When you finish viewing
		the file, you can reopen the original file.  The last location
		and breakpoints will still be marked when you return.

		You may not need to open a new file to see source files for a
		different module of your program.  The CodeView debugger auto-
		matically switches to the source file of a module when program
		execution enters that module.  Although switching source files
		is never necessary, it may be desirable if you want to set
		breakpoints or execute to a line in a module not currently
		being executed.
----
Note
----
If the debugger cannot find the source file when it swit-
ches modules, a dialog box appears asking for a file spec-
fication for the source file.  You can either enter a new
file specification if the file is in another directory, or
press the ENTER key if no source file exists.  If you press
the ENTER key, the module can only be debugged in assembly
mode.
====

DOS 	Exits to a DOS shell.  This brings up the DOS screen, where
Shell	you can execute DOS commands or executable files.  To return
	to the CodeView debugger, type exit at the DOS command prompt.
	The CodeView screen reappears with the same status it had when
	you left it.

	The Shell Escape command works by saving the current processes
	in memory and then executing a second copy of COMMAND.COM. This
	requires more than 200K of free memory, since the debugger,
	COMMAND.COM, symbol tables, and the debugged program must all
	be saved in memory.  If you do not have enough memory to exe-
	cute the Shell Escape command, an error message appears.  Even
	if you have enough memory to execute the command, you may not
	have enough memory left to execute large programs from the
	shell.

	The Shell Escape command does not work under certain condi-
	tions.  See Section 11.7 for additional information.

Exit	Terminates the debugger and returns to DOS.

2.1.3.2  The View Menu

The View menu includes selections for switching between source and assembly
modes, and for switching between the debugging screen and the output screen.
The corresponding function keys for menu selection are shown on the right side
of the menu where appropriate.  The View menu is shown in Figure 2.3, and the
selections are explained below.

----
Note
----
The terms "source mode" and "assembly mode" apply to Microsoft Macro
Assembler programs as well as to high level language programs.  Source
mode used with assembler programs shows the source code as originally
written, including comments and directives.  Assembly mode displays
unassembled machine code, without symbolic information.

The use of one mode or another affects Trace and Program Step commands, as
explained in Chapter 5, "Executing Code."
====

At all times exactly ONE of the following selections will have a small double
arrow to the left of the name: Source, Mixed, and Assembly.  This arrow
indicates which of the three display modes is in use.  If you select a mode
when you are already in that mode, the selection will be ignored.  The
Registers selection may or may not have a double arrow to the left, depending
on whether or not the register window is being displayed.

Selection    Action
-------------------
Source		Changes to source mode (showing source lines only).

Mixed		Changes to mixed mode (showing both unassembled machine code
		and source lines).

Assembly	Changes to assembly mode(showing only unassembled machine
		code).
Registers	Selecting this option will toggle the register window on and
		off.  You can also turn the register on and off by pressing
		the F2 key.

Output		Selecting this option will display the output screen.  The
		entire CodeView display will temporarily disappear, but come
		back as soon as you press any key.  The Output command can
		also be selected with the F4 key.

2.1.3.3  The Search Menu

The Search menu includes selections for searching through text files for text
strings and for searching executable code for labels.  The Search menu is
shown in Figure 2.4 and the selections are explained below.

Selection	Action
---------------------
Find...		Searches the current source file or other text file for a
		specified regular expression. (This selection can also be made
		without pulling down a menu, simply by pressing CONTROL+F.)

		When you make this selection, a dialog box opens, asking you
		to enter a regular expression.  Type the expression you want
		to search for and press the ENTER key.  The CodeView debugger
		starts at the current or most recent cursor position in the
		display window and searches for the expression.

		If your entry is found, the cursor moves to the first source
		line containing the expression.  If you are in assembly mode,
		the debugger automatically switches to source mode when the
		expression is found.  If the entry is not found, a message box
		opens telling you the problem and asking you to press a key
		(you can also click a mouse button) to continue.

		Regular expressions are a method of specifying variable text
		strings.  This method is similar to the DOS method of using
		wild cards in file names.  Regular expressions are explained
		in detail in Appendix B.

		You can use the Search selections without understanding
		regular expressions.  Since text strings are the simplest form
		of regular expressions, you can simply enter a string of
		characters as the expression you want to find.  For example,
		you could enter count if you want to search for the word
		"count."

		The following characters have a special meaning in regular
		expressions: Backslash(\), asterisk (*), left bracket ([),
		period (.), dollar sign ($), and caret (^).  In order to find 
		strings containing these characters, you must precede the
		characters with a backslash; this cancels their special
		meanings.
		For example, the periods in FORTRAN relational and logical
		operators must be preceded by backslashes.  You would use \.EQ
		to find the .EQ. operator.  With C, you would use \*ptr to
		find *ptr; and with BASIC, you would use NAME\$ to find NAME$.

		The Case Sense selection from the Options menu has no effect
		on searching for regular expressions.

Next		Searches for the next match of the current regular expression.

		This selection is meaningful only after you have used the
		Search command to specify the current regular expression.  If
		CodeView debugger searches to the end of the file without
		finding another match for the expression, it wraps around and
		starts searching at the beginning of the file.

Previous	Searches for the previous match of the current regular
		expression.

		This selection is meaningful only after you have used the
		Search command to specify the current regular expression. If
		the debugger searches to the beginning of the file without
		finding another match for the expression, it wraps around and
		starts searching at the end of the file.

Label...	Searches the executable code for an assembly language label.

		If the label is found, the cursor moves to the instruction
		containing the label.  If you start the search in source mode,
		the debugger will switch to assembly mode to show a label in a
		library routine or an assembly language module.

2.1.3.4  The Run Menu

The Run menu includes selections for running your program.  The Run menu is
shown in Figure 2.5, and the selections are explained below.

Selection	Action
---------------------
Start		Starts the program from the beginning and runs it.

		Any previously set breakpoints or watch statements will still
		be in effect.  The CodeView debugger will run your program
		from the beginning to the first breakpoint, or to the end of
		the program if no breakpoint is encountered.  This has the
		same effect as selecting Restart (see the next selection),
		then entering the Go command.

Restart		Restarts the current program, but does not begin executing it.

		You can debug the program again from the beginning.  Any
		previously set breakpoints or watch statements will still be
		in effect.

Execute		Executes in slow motion from the current instruction.
		This is the same as the Execute dialog command (E).
		To stop execution, press any key or a mouse button.

Clear		Clears all breakpoints.
Breakpoints	
		This selection may be convenient after selecting Restart if
		you don't want to use previously set breakpoints.  Note that
		watch statements are not cleared by this command.
----
Note
----
Although "Start" and "Restart" retain breakpoints, along with pass count
and arguments (see Chapter 5, "Executing Code"), any instructions entered
with the Assemble command will be overwritten by the original program.
====

2.1.3.5  The Watch Menu

The Watch menu includes selections for managing the watch window.  Selections
on this menu are also available with dialog commands.  The Watch menu is shown
in Figure 2.6, and the selections are explained below.

Selection	Action
---------------------
Add Watch...	Adds a watch-expression statement to the watch window. (This
		selection can also be made directly, byi pressing CONTROL+W.)

		A dialog window opens, asking for the source-level expression
		(which may be simply a variable) whose value you want to see
		displayed in the watch window.  Type the expression and press
		the ENTER key or a mouse button.  The statement appears in the
		watch window in normal text.  You cannot specify a memory
		range to be displayed with the Add Watch selection as with the
		Watch dialog command.

		You can sepcify the format in which the value will be
		displayed.  Type the expression, followed by a comma and a
		CodeView format specifier.  If you do not give a format
		specifier, the CodeView debugger displays the value in a
		default format.  See Chapter 6, "Examining Data and
		Expressions," for more information about format specifiers and
		the default format.  See Section 8.1, "Setting Watch-
		Expression and Watch-Memory Statements," for more information
		about the Watch command.

Watchpoint...	Adds a watchpoint statement to the window.

		A dialog window opens, asking for the source-level expression
		whose value you want to test.  The watchpoint statement appears
		in the watch window in high-intensity text when you enter the
		expression.  A watchpoint is a conditional breakpoint that
		causes execution to stop when the expression becomes nonzero
		(true). See Section 8.2, "Settting Watch-points," for more
		information.

Tracepoint...	Adds a tracepoint statement to the watch window.

		A dialog window opens, asking for the source-level expression
		or memory range whose value you want to test.  The tracepoint    
		statement appears in the watch window in high-intensity text
		when you enter the expression.  A tracepoint is a conditional
		breakpoint that causes execution to stop when the value of a
		given expression changes.  You cannot specify a memory range
		to be tested with the Tracepoint selection as you can with the
		Tracepoint dialog command.

		When setting a tracepoint expression, you can specify the
		format in which the value will be displayed.  After the
		expression type a comma and a format specifier.  If you do not
		give a format specifier, the CodeView debugger displays the
		value in a default format.  See Chapter 6, "Examining Data and
		Expressions," for more information about format specifiers and
		default.  See Section 8.3, "Setting Tracepoints," for more
		information about tracepoints.

Delete Watch...Deletes a statement from the watch window. (This selection can
		also be made directly, by pressing CONTROL+U.)

		A dialog window opens, showing the current watch statements.
		If you are using the keyboard, press the UP ARROW or DOWN ARROW
		key to move the highlight to the statement you want to delete,
		then press the ENTER key.

Delete All Watch -- Deletes all statements in the watch window.

		All watch, watchpoint, and tracepoint statements are deleted,
		the watch window disappears, and the display window is redrawn
		to take advantage of the freed space onscreen.

2.1.3.6  The Options Menu

The Options menu allows you to set options that affect various aspects of the
behavior of the CodeView debugger.  The Options menu is shown in Figure 2.7,
and the selections are explained below.

Selections on the Options menu have small double arrows to the left of the
selection name when the option is on.  The status of the option (and the
presence of the double arrows) is reversed each time you select the option.
By default, the Flip/Swap and Bytes Coded options are on, and the 386 option
is off, when you start the CodeView debugger.  Depending on which language
your main program jis in, the debugger will automatically turn Case Sense on
(if your program is in C) or off (if your program is in another language) when
you start debugging.

The selections from the Options menu are discussed below.

Selection	Action
---------------------
Flip/Swap	When on (the default), screen swapping or screen flipping
		(whichever the debugger was started with) is active; when off
		swapping or flipping is disabled.

		Turning off swapping or flipping makes the screen scroll more
		smoothly.  You will not see the program flip or swap each time
		you execute part of the program.  This option has no effect
		if neither swapping nor flipping was selected during startup.
------
Warning
-------
Any time your program writes to the screen, make sure that flipping or
swapping is on.  If swapping and flipping are off, your program will write
the output at the location of the cursor.  The CodeView debugger will
detect that the screen has changed and will redraw the screen, thus
destroying the program output.  An error message is also displayed:
Flip/Swap option off - application output lost.
=======

Bytes Coded	When on (the defaultf), the instructions, instruction
		addresses, and the bytes for each instruction are shown; when
		off, only the instructions are shown.  This option affects
		only assembly mode.  The following display shows the appear-
		ance of sample code when the option is off:

		27:       name = gets(namebuf);
			LEA       AX,Word ptr [namebuf]
			PUSH      AX
			CALL      _gets (03E1)
			ADD       SP,02
			MOV       Word Ptr [name],AX

		The following display shows the appearance of the same code
		when the option is on:

 		27:       name = gets(namebuf);
		32AF:003E 8D46E          LEA     AX,Word Ptr [namebuf]
		32AF:0041 50             PUSH    AX
		32AF:0042 E89C03         CALL    _gets (03E1)
		32AF:0045 83C402         ADD     SP,02
		32AF:0048 8946DA         MOV     Word Ptr [name],AX

Case Sense	When the selection is turned on, the CodeView debugger assumes
		that symbol names are case sensitive (each lowercase letter is
		different from the correspondig uppercase letter); when off,
		symbol names are not case sensitive.

		This option is on by default for C programs, and off by
		default for FORTRAN, BASIC, and assembly programs.  You will
		probably want to leave the  option in its default setting.

386		When on, the register window will display the registers in the
		wider 386 format.  Furthermore, this option will enable you to
		assemble and execute instructions that reference 32-bit regis-
		ters.  If the 386 option is not on, then any data stored in
		the high-order word of a 32-bit register will be lost.

		To use this option, you should have a 386 processor running in
		386 mode.  If you do not have a 386 processor, then the debug-
		ger will respond with the message "CPU is not an 80386" and
		leave the option turned off.

2.1.3.7  The Language Menu

The Language menu allows you either to select the expression evaluator, or to
instruct the CodeView debugger to select it for you automatically.  The
Language menu is shown in Figure 2.8 and the selections are explained below.
As with the Options menu, the selection ON is marked by double arrows.  Unlike
the Options menu, however, exactly one item (and no more) on the Language menu
is selected at any given time.

The Auto selection causes the debugger to select automatically the expression
evaluator each time a new source file is loaded.  The debugger will examine
the extension of the source file in order to determine which expression
evaluator to select.  The Auto selection will use the C expression evaluator
if the current source file does not have a .BAS, .F, .FOR, or .PAS extension.

If you change to a source module with an .ASM extension, then Auto will cause
the debugger to select the C expression evaluator, but not all of the C
defaults will be used; system radix will be hexadecimal, case sensitivity will
be turned off, and the register window will be displayed.

When a language expression evaluator is selected, the debugger uses that
evaluator, regardless of what kind of program jis being debugged.

2.1.3.8  The Calls Menu

The Calls menu is different from other menus in that its contents and size
change, depending on the status of your program.  The Calls menu is shown in
Figure 2.9.  The mnemonic for each item in the Calls menu is a number.  Type
the number displayed immediately to the left of a routine in order to select
it.  You can also use the UP ARROW or DOWN ARROW key to move to your
selection, and then press the ENTER key.  You can use the mouse to select
from the Calls menu as well.

The effect of making a selection from the Calls menu is to view a routine.
The cursor will go to the line at which the selected routine was last exe-
cuting.  For example, selecting main in the Example above will cause CodeView
to display main, at the point at which main made a call to calc (the function
immediately above it).  Note that selecting a routine from the Calls menu does
not (by itself) affect program execution.  It simply provides a convenient way
to view previously called routines.

It is not required that one of the routines be selected.  The Calls menu is
useful simply for viewing the list of previously called routines.

The Calls menu shows the current routine and the trail of routines from which
it was called.  The current routine is always at the top.  The routine from
which the current routine was called is directly below.  Other active routines
are shown in the reverse order in which they were called.  With C and FORTRAN
programs, the bottom routine should always be main. (The only time when main
will not be the bottom routine is when you are tracing through the standard
library's startup or termination routines.)

The current value of each argument, if any, is shown in parentheses following
the routine.  The menu expands to accommodate the arguments of the widest
routine.  Arguments are shown in the current radix (the default is decimal).
If there are more active routines than will fit on the screen, or if the
routine arguments are too wide, the display will expand to both the left and
right.  The Stack Trace dialog command (K) also shows all the routines and
arguments.

---
Note
----
If you are using the CodeView debugger to debug assembly language programs,
routines will be shown in the Calls menu only if they use one of the Micro-
soft calling conventions.  These calling conventions are explained in the
Microsoft Mixed-Language Programming Guide.
====

2.1.3.9  The Help Menu

The Help menu lists the major topics in the help system.  For help, open the
Help menu and then select the topic you want to view.

Each topic may have any number of subtopics.  You must go to the major topic
first.  Information on how to move around within the help system is provided
in the next section.

The bottom selection on the Help menu is the About command.  When you make
this selection, the debugger will display a small box at the center of the
screen that gives the time, the name of the product, and the version number.

2.1.4  Using the Help System

The CodeView on-line help system uses tree-structured menus to give you quick
access to help screens on a variety of subjects.  The system uses a combin-
ation of menu access and sequentially linked screens, as explained below.

The help file is called CV.HLP. It must be present in the current directory or
in one of the directories specified with the DOS PATH command.  If the help
file is not found, the CodeView debugger will still operate, but you will not
be able to use the help system.  An error message will appear if you try to
use a help command.

When you request help, either by pressing the F1 key, by using the H dialog
command, or by selecting the Help menu, the first help screen appears.  You
can select Next and Previous buttons to page through the screens.  The
screens are arranged in a circular fashion, so that selecting Next on the last
screen get you to the first screen.  Select the Cancel button to return to
the CodeView screen.  Pressing the PGDN, PGUP, and ESC keys achieves the same
results as selecting Next, Previous, and Cancel, respectively, with the mouse.

You can enter the help system at a particular topic by selecting the topic from
the Help menu.  Once into the system, use Next and Previous to page to
other screens.

2.2  Using Sequential Mode

Sequential mode is required if you have neither an IBM Personal Computer nor a
closely compatible computer.  In sequential mode, the CodeView debugger works
much like its predecessors, the Microsoft Symbolic Debug Utility (SYMDEB) and
the DOS DEBUG utility.  Sequential mode is also useful when you are using
redirected CodeView input and output.

In sequential mode, the CodeView debugger's input and output always move down
the screen from the current location.  When the screen is full, the old output
scrolls off the top of the screen to make room for new output appearing at the
bottom.  You can never return to examine previous commands once they scroll
off, but in many cases, you can reenter the command to put the same inform-
ation on the screen again.

Most window commands cannot be used in sequential mode.  However, the
following function keys, which are used as commands in window mode, are also
available in sequential mode.

Command		Action
---------------------
F1		Displays a command-syntax summary.

F2		Displays the registers.
		This is equivalent to the Register (R) dialog command.

F3		Toggles between source, mixed, and assembly modes.

		Pressing this key will rotate the mode between source, mixed,
		and assembly.  You can achieve the same effect by using the
		Set Assembly (S-), Set Mixed (S&), and Set Source (S+) dialog
		commands.

F4		Switches to the output screen, which shows the output of your
		program.  Press any key to return to the CodeView debugging
		screen.  This is equivalent to the Screen Exchange (\) dialog
		command.

F5		Executes from the current instruction until a breakpoint or
		the end of the program is encountered.  This is equivalent to
		the Go dialog command (G) with no argument.

F8		Executes the next source line in source mode, or the next in-
		struction in assembly mode.

		If the source line or instruction contains a function, pro-
		cedure, or interrupt call, the CodeView debugger executes the
		first source line of the call and is ready to execute the next
		source line or instruction within the call.  This is equival-
		ent to the Trace (T) dialog command.
F9		Sets or clears a breakpoint at the current program location.

		If the current program location has no breakpoint, one is set.
		If the current location has a breakpoint, it is removed.  This
		is equivalent to the Breakpoint Set (BP) dialog command with
		no argument.

F10		Executes the next source line in source mode, or the next
		instruction in assembly mode.

		If the source line or instruction contains a function,
		procedure, or interrupt call, the call is executed to the end,
		and the CodeView debugger is ready to execute the line or
		instruction after the call.  This is equivalent to the Program
		Step (P) dialog command.

The CodeView Watch (W), Watchpoint (WP), and Tracepoint (TP) commands work in
sequential mode, but since there is no watch window, the watch statements are
not shown.  You must use the Watch List command (W) to examine watch
statements and watch values.  See Chapter 8 for information on Watch
Statement commands.

All the CodeView commands that affect program operation (such as Trace, Go,
and Breakpoint Set) are available in sequential mode.  Any debugging oper-
ation done in window mode can also be done in sequential mode.


.end of chapter.